Skip to content

module api 2.1 docs#66

Merged
Julusian merged 10 commits into
mainfrom
feat/module-api-2.1
Jun 27, 2026
Merged

module api 2.1 docs#66
Julusian merged 10 commits into
mainfrom
feat/module-api-2.1

Conversation

@Julusian

@Julusian Julusian commented May 24, 2026

Copy link
Copy Markdown
Member

Some drafting of the api changelog for 2.1

Summary by CodeRabbit

  • Documentation

    • Expanded developer and user guides for expressions, scripting, arrays, objects, and multi-line syntax.
    • Added new documentation for layered presets, graphics elements, composite elements, feedback behavior, and variable image support.
    • Updated Node.js runtime guidance and preset ordering/reference materials.
    • Added API 2.1/Companion 5.0+ documentation covering cancellation, results, alternatives, and advanced styling guidance.
  • Chores

    • Updated CI workflows to use a newer repository checkout action.

@coderabbitai

coderabbitai Bot commented May 24, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@Julusian, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 46 minutes and 24 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f909ba6c-1d91-4131-84db-7a9ed1d9f8ab

📥 Commits

Reviewing files that changed from the base of the PR and between 5b69fcc and e996ecc.

📒 Files selected for processing (2)
  • for-developers/module-development/api-changes/v2.1.md
  • for-developers/module-development/connection-basics/presets.md
📝 Walkthrough

Walkthrough

Adds Companion 5.0 / API 2.1 documentation covering graphics elements, composite elements, layered preset overhaul, AbortSignal cancellation, action results, feedback affectedProperties, Node 26 runtime support, and expanded user-facing expression scripting docs. CI checkout action is bumped from v6 to v7.

Changes

API 2.1 & Module Development Docs

Layer / File(s) Summary
API 2.1 changelog overview
for-developers/module-development/api-changes/v2.1.md
New page covering all API 2.1 changes: subscribe typing, AbortSignal, action results, graphics/composites, internal presets, feedback-driven local variables, alternatives, affectedProperties, and Node 26.
Graphics elements reference page
for-developers/module-development/connection-basics/graphics-elements.md
New page documenting the full element-based drawing system with coordinate conventions, expression-or-value syntax, all element types (text, image, box, line, circle, gauge, group, composite), shared border properties, and canvas configuration.
Composite elements reference page
for-developers/module-development/connection-basics/composite-elements.md
New page documenting setCompositeElementDefinitions(), the definition schema, referencing composites from layered presets, UI availability, validation, and TypeScript typing propagation.
Preset definitions doc overhaul
for-developers/module-development/connection-basics/presets.md, for-developers/module-development/connection-basics/presets-1.x.md
Updates presets.md to document simple/layered preset types, alternatives, feedback-driven local variables, internal actions/feedbacks, logic building blocks, per-element styleOverrides, and sidebar reordering.
Actions & feedbacks: AbortSignal, results, affectedProperties
for-developers/module-development/connection-basics/actions.md, for-developers/module-development/connection-basics/feedbacks.md
Adds API 2.1 AbortSignal cancellation guidance for actions/feedbacks/learn, hasResult action return docs, affectedProperties requirement, and data-URI image feedback return tip.
Variables data-URI tip & Node 26 runtime docs
for-developers/module-development/connection-basics/variables.md, for-developers/module-development/module-lifecycle/updating-nodejs.md, for-developers/module-development/module-setup/manifest.json.md
Adds data-URI image variable tip; documents node26 as a valid runtime.type value with API 2.1 context in both manifest and updating-nodejs guides.

User-Facing Expression & Scripting Docs

Layer / File(s) Summary
Expression index: multi-line, optional chaining, 5.0 notes
user-guide/4_expressions/index.md
Adds multi-line/temporary variable rules, optional chaining and spread examples, a "Going further" pointer, and Companion 5.0 language subset/compatibility notes.
Array iteration & object helpers
user-guide/4_expressions/functions.md
Adds Array iteration operations section documenting arrayMap, arrayFilter, arrayReduce, arrayForEach, arrayFind/FindIndex, arraySome/Every, arraySort, arrayReverse, objectKeys, and objectValues.
New advanced expressions / scripting page
user-guide/4_expressions/scripting.md
New page documenting variables and scope, control flow, arrow functions, collection helpers, execution limits, and worked examples for Companion expression scripting.

CI Checkout Action Bump

Layer / File(s) Summary
Bump actions/checkout to v7
.github/workflows/build-pr.yaml, .github/workflows/deploy.yaml, .github/workflows/lint.yaml
Bumps the checkout action from v6 to v7 in all three workflow files.

Poem

🎨 New elements layer up with grace,
gauge and composite find their place.
AbortSignals fly, results return,
Node 26 joins — so much to learn!
Scripts and arrays now dance in line,
Companion 5.0 — looking fine! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title is related to the changes, but it is very generic and does not clearly summarize the main update. Use a more specific title, such as the main doc theme or feature area updated for API 2.1.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@Julusian Julusian changed the title first pass of 2.1 docs first pass of api 2.1 docs May 27, 2026
@Julusian Julusian force-pushed the feat/module-api-2.1 branch from 21fc6c7 to 0f23a08 Compare June 15, 2026 20:23
@Julusian Julusian force-pushed the feat/module-api-2.1 branch from 0f23a08 to 0ad03ae Compare June 19, 2026 13:38
Julusian and others added 6 commits June 19, 2026 20:44
Bumps [actions/checkout](https://github.com/actions/checkout) from 6 to 7.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@v6...v7)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
@Julusian Julusian changed the title first pass of api 2.1 docs module api 2.1 docs Jun 27, 2026
@Julusian Julusian marked this pull request as ready for review June 27, 2026 15:03

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (5)
for-developers/module-development/api-changes/v2.1.md (2)

110-151: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Minor: Element type list consistency check.

The graphics overhaul lists 8 element types (text, image, box, line, circle, gauge, group, composite). This matches graphics-elements.md which documents all 8. ✅

One small thing: the "Gauge" description says "value-driven bar/ring meter" but graphics-elements.md also documents orientation: 'horizontal' | 'vertical' | 'ring' — the "bar" covers horizontal/vertical but you might want to be explicit that gauges can be horizontal bars, vertical bars, or rings. Not a blocker, just a thought for clarity.


226-226: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Style: "all of the functionality" → "all the functionality"

LanguageTool suggests removing "of" for conciseness. This is a minor style point — "all the functionality" reads more naturally.

- fallback for hosts which don't support all of the functionality of the module API (such as Bitfocus Buttons).
+ fallback for hosts which don't support all the functionality of the module API (such as Bitfocus Buttons).
for-developers/module-development/connection-basics/presets.md (2)

247-309: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! The internal actions and feedbacks documentation is comprehensive and matches v2.1.md. The example using internal:wait, internal:logicIf, and internal:customLog demonstrates real usage.

One minor note: the code example at lines 272-304 uses ;[ which is slightly unusual — it's to avoid ASI issues with the leading [. This is fine but might confuse some readers. Maybe add a brief comment?

  ```ts
- ;[
+ // Note the leading semicolon to avoid automatic semicolon insertion issues
+ ;[
    {

388-423: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

LGTM! The alternatives section matches v2.1.md and provides a good layered+simple fallback example.

Addressing the static analysis hint at line 392:

- fallback for hosts with a more restrictive drawing, or don't support all of the functionality of the module API (such as Bitfocus Buttons).
+ fallback for hosts with a more restrictive drawing, or don't support all the functionality of the module API (such as Bitfocus Buttons).
user-guide/4_expressions/functions.md (1)

349-388: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider clarifying objectKeys/objectValues behavior with arrays.

The docs note these work on "an object (or array)". For arrays, objectKeys returns string indices ("0", "1"...) which can surprise users expecting numeric indices. A brief note or example would help avoid confusion.


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 123b2b54-6b02-4208-b461-d4b02c05a245

📥 Commits

Reviewing files that changed from the base of the PR and between 02dc342 and 5b69fcc.

📒 Files selected for processing (16)
  • .github/workflows/build-pr.yaml
  • .github/workflows/deploy.yaml
  • .github/workflows/lint.yaml
  • for-developers/module-development/api-changes/v2.1.md
  • for-developers/module-development/connection-basics/actions.md
  • for-developers/module-development/connection-basics/composite-elements.md
  • for-developers/module-development/connection-basics/feedbacks.md
  • for-developers/module-development/connection-basics/graphics-elements.md
  • for-developers/module-development/connection-basics/presets-1.x.md
  • for-developers/module-development/connection-basics/presets.md
  • for-developers/module-development/connection-basics/variables.md
  • for-developers/module-development/module-lifecycle/updating-nodejs.md
  • for-developers/module-development/module-setup/manifest.json.md
  • user-guide/4_expressions/functions.md
  • user-guide/4_expressions/index.md
  • user-guide/4_expressions/scripting.md

Comment thread .github/workflows/build-pr.yaml
Comment thread .github/workflows/deploy.yaml
Comment thread .github/workflows/lint.yaml
Comment thread user-guide/4_expressions/index.md
Comment thread user-guide/4_expressions/scripting.md
@Julusian Julusian merged commit 1ac7571 into main Jun 27, 2026
7 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant